feat(interfaces): look up a Platform quorum at its signed Core height - #8069

Issue being fixed or feature implemented

interfaces::LLMQ::getPlatformQuorums(type) returns every retained Platform quorum key (1440 on mainnet) with no notion of when each quorum could sign. A Platform proof verifier built on it has two problems:

• It accepts state signed by any retained quorum, even one that was never in the signing set at the state's Core height.
• It cannot tell "this quorum could not have signed" from "this node cannot tell yet". An empty or short list looks the same whether the node is behind, has a damaged LLMQ index, or the proof is really bad. A verifier that bans endpoints on failure would then ban honest ones.

Nothing on develop calls getPlatformQuorums outside its unit test. Its intended consumer is the DashPay GUI's Platform client, which verifies Drive proofs whose signed metadata carries core_chain_locked_height.

What was done?

getPlatformQuorum(llmq_type, quorum_hash, core_chain_locked_height) replaces getPlatformQuorums and the PlatformQuorum struct. It returns FOUND (with the 48-byte basic-scheme key), INVALID or UNAVAILABLE.

Let h be the signed height and N the Platform type's signingActiveQuorumCount. A quorum may sign for E DKG intervals: its signing-active period plus a slack of two, so E = N + 2 for a non-rotating type and 1 + 2 for a rotating one. The window is the newest commitments mined at or below h covering those E intervals: N + 2 entries for a non-rotating type, and 3 · N for a rotating one, read cycle by cycle across its quorum indexes. W = E · dkgInterval is 624 blocks on mainnet and testnet.

FOUND — the quorum is in the window and its commitment record is consistent: the key is copied out.

INVALID — the local chain proves the quorum could not have signed:

• the type is not the Platform type;
• h > INT32_MAX;
• h is more than W below the best ChainLock this node knows, clamped to the tip;
• the hash is no block of the active chain below h, so no quorum with it can have been mined at or below h — counted only when the window was read in full and the active chain's block at h is, or is an ancestor of, the block of the best ChainLock whose block this node knows.

UNAVAILABLE — everything else, including:

• node services are missing, or h is above the tip;
• h is more than W below the tip but no ChainLock is known. After a restart during a ChainLock stall, Platform may still carry the stalled ChainLock this node has not learned yet;
• a quorum mined at or below h that is not in the window. Platform verifies a block against its last committed validator set, and Tenderdash installs a new set only when it commits, so after a Core-height jump the first Platform block carrying the new height is signed by the outgoing quorum, however far behind the window it has fallen;
• the window could not be read in full, or no ChainLock this node knows the block of locks the block at h (none is known yet, h is above it, or it is on a branch that forks below h). Above a ChainLock the active chain may be a competing branch, and a ChainLock height alone cannot rule that out: a CLSIG can name a block this node does not know, or a branch it has not activated yet;
• the selected commitment record cannot be read (a LevelDB error), is missing, belongs to another quorum or type, was mined off the active chain or above h, or carries an invalid key. Mined commitments passed consensus validation, so those record states are local faults, never evidence against the quorum. A database read error is answered, not thrown.

A quorum found in the window is answered regardless of ChainLock coverage. A lookup reads at most N + 2 index entries (non-rotating) and one commitment record. It does not build CQuorum objects and keeps no cache.

CQuorumBlockProcessor::ScanMinedCommitmentsUntilBlock (plus an indexed variant for rotation-enabled types) returns the same quorum bases as GetMinedCommitments[Indexed]UntilBlock, plus a complete flag.

• The existing walkers stop silently on an unreadable entry, and assert on an impossible one.
• The new scan instead reports complete = false when an entry inside the type's key range:
  • cannot be read: it does not deserialize, LevelDB reports a read error, or the iterator stepped over a table block that failed its checksum;
  • or cannot be trusted: an impossible base height, or bases that do not strictly decrease along the index or repeat across quorum indexes. Strict decrease holds because a commitment is mined within its own quorum's DKG interval.
• It keeps the bases read before the fault, except those a contradiction implicates: of a pair that does not decrease, or two entries naming the same base, either may be the wrong one, so neither is returned (in the indexed scan, including one an earlier cycle had already taken).
• It treats a key outside the range as the end of the index; the key prefix is compared before anything is deserialized.
• Once the window is full, no further entry or iterator status decides coverage.
• Non-indexed bases are newest first; indexed bases are by cycle rank, newest first, then by quorum index.
• Existing callers are unchanged.

CDBIterator::HasError() (forwarded by CDBTransactionIterator) exposes LevelDB's iterator status. Without it, a corrupt block that LevelDB skipped reads the same as the end of the data.

llmq::PlatformEligibleIntervals, PlatformEligibleQuorumCount and PlatformQuorumMinSignedHeight are the window and the staleness bound as pure functions. The bound follows the ChainLock rather than the tip, so state signed before a ChainLock stall stays verifiable while the tip moves on.

How Has This Been Tested?

Unit tests, all passing (test_dash --run_test=interfaces_tests,llmq_params_tests,llmq_blockprocessor_tests):

• interfaces_tests/getPlatformQuorum:
  • the newest quorum's key and its byte order;
  • the edges of the window, and a quorum fourth at height 50 that is fifth after a Core-height jump to the tip (FOUND, then UNAVAILABLE);
  • a historical quorum;
  • the staleness edge: below the tip's bound with no ChainLock (UNAVAILABLE), with one (INVALID), and after learning a stalled ChainLock (FOUND);
  • a ChainLock ahead of the tip;
  • absence and ChainLocks: no ChainLock; at, just above and far above a ChainLock (where a present quorum is still FOUND); below a ChainLock on an unknown block; above and below the fork of a ChainLock on a competing branch; below a ChainLock on a header beyond the tip;
  • provably never mined: a random hash, a block at or above h, a header off the active chain (INVALID); an active block below h outside the window (UNAVAILABLE);
  • rejected inputs: above the tip, beyond int32, a non-Platform type, an unknown type.
• interfaces_tests/getPlatformQuorum_local_faults: every local-fault state listed above, unreadable index entries both before and after the requested quorum, a duplicate index entry (an unknown quorum is UNAVAILABLE while it is there), and an index entry naming a valid older quorum that the next entry contradicts (UNAVAILABLE, FOUND once repaired). The tip is chain-locked, so these rows observe the fault rather than missing ChainLock coverage, and a healthy-window control is INVALID.
• interfaces_tests/getPlatformQuorum_disk_faults: an on-disk EvoDB, compacted, with one LevelDB table block corrupted, then reopened. A corrupt index block gives UNAVAILABLE for quorums in and behind it, and FOUND ahead of and below it. A corrupt block holding the selected commitment record gives UNAVAILABLE.
• llmq_params_tests/platform_quorum_min_signed_height_test: the mainnet/testnet and regtest bounds, the ChainLock-stall case, a young chain, overflow, and rotating types (llmq_60_75: 96 quorums over 864 blocks; llmq_test_dip0024: 6 over 72).
• llmq_blockprocessor_tests/scan_mined_commitments_*:
  • a full window, a young chain and corrupt entries;
  • an impossible base height, a duplicate base, an out-of-order base (both entries left out, an earlier one kept), and a base repeated across quorum indexes;
  • in the indexed scan, a contradiction met in the second cycle drops the base the first cycle took;
  • a corrupt table block on disk: the walk stops before it, but a window filled earlier, or a walk starting below it, is complete;
  • the end of a type's key range;
  • the indexed order compared against GetMinedCommitmentsIndexedUntilBlock.

A rotating Platform type can only be selected on devnets (-llmqplatform), which the unit-test fixtures do not run, so the rotating window is covered through the pure functions and the indexed scan rather than through getPlatformQuorum.

Fail-before evidence:

• Against develop's sources, the new tests do not compile.
• Against the previous revision of this PR, the new tests give 13 failing checks: the no-ChainLock staleness row, the two out-of-window rows, the contradicted-base lookup, five scan rows, and four rotating-window rows.
• Targeted mutations were built and run. Each of these makes its matching check fail: restoring INVALID for a height stale only against the tip; treating every hash missing from the window as never mined; dropping the clean-window requirement; keeping the base a contradiction implicates; keeping a base the indexed scan took in an earlier cycle; keeping a repeated base; counting the slack in entries; removing the ordering check. Earlier revisions of this PR ran the same treatment for the staleness bound, the ChainLock clamp and anchor rule, each record check, the prefix-before-parse order, the iterator-status check and the cross-index check.
• The scan's catch of a database error while re-reading an index value has no regression test. With the iterator status checked first, that read hits the same checksummed block, so it can only fail on a transient I/O error.

Builds: Linux x86_64, gcc-11 with --enable-werror (full build at both commits, make check), and clang-19 with --enable-debug --enable-werror (including -Wthread-safety). clang-tidy-19 with the repository configuration reports nothing for the touched files. The lints were run, including lint-circular-dependencies.py.

Rebased onto develop 4c5c015, which now runs clang-tidy over unit tests too: BaseHeights in llmq_blockprocessor_tests reserves its vector, clang-tidy 19 reports nothing on the changed .cpp files, and llmq_blockprocessor_tests, interfaces_tests and llmq_params_tests pass on the new base.

Breaking Changes

interfaces::LLMQ::getPlatformQuorums and interfaces::LLMQ::PlatformQuorum are removed. They had no caller outside their unit test. No RPC, P2P, consensus or on-disk format changes.

Residual behaviour, by design:

• After a Platform Core-height jump of more than two DKG intervals, proofs from the one Platform block that first carries the new height are UNAVAILABLE until the next Platform block, which the new validator set signs. Nothing is banned.
• A proof naming a real quorum that left the window is UNAVAILABLE, never accepted; an endpoint serving one is not banned for it.
• Above the best ChainLock whose block this node knows, and on a node that knows none (after a restart, until its first ChainLock), a missing quorum and a height stale only against the tip are UNAVAILABLE rather than INVALID. An honest endpoint is never penalized for this node's fork or lag; a bad proof is retried rather than rejected meanwhile.
• An index entry that is wrong but fits the index's order is not detected. It cannot make a quorum INVALID, but it can make one just outside the window FOUND, or one inside it UNAVAILABLE. Detecting one would mean reading every record in the window. LevelDB checksums catch media corruption, so such an entry can only come from a software bug in the index writer.
• The existing GetMinedCommitments* walkers used by consensus still stop silently at a corrupt block. That is unchanged here.
• Platform state whose Core height lags this node's ChainLock by more than W (about 26 hours) is rejected.

Checklist:

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• I have assigned this pull request to a milestone (if you have permission to set one)

🤖 Generated with Claude Code